---
title: Toggle Group
description: Using the toggle-group machine in your project.
package: "@zag-js/toggle-group"
---

A toggle group is used to toggle either one option or multiple options.

<Resources pkg="@zag-js/toggle-group" />

<Showcase id="ToggleGroup" />

**Features**

- Fully managed keyboard navigation
- Supports horizontal and vertical orientation
- Support for multiple selection

## Installation

To use the toggle group machine in your project, run the following command in
your command line:

<CodeSnippet id="toggle-group/installation.mdx" />

## Anatomy

To set up the toggle group correctly, you'll need to understand its anatomy and
how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="toggle-group" />

## Usage

First, import the toggle group package into your project

```jsx
import * as toggle from "@zag-js/toggle-group"
```

The toggle group package exports two key functions:

- `machine` — The state machine logic for the toggle group widget as described
  in the WAI-ARIA spec.
- `connect` — The function that translates the machine's state to JSX attributes
  and event handlers.

> You'll need to provide a unique `id` to the `useMachine` hook. This is used to
> ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the
toggle group machine in your project 🔥

<CodeSnippet id="toggle-group/usage.mdx" />

### Changing the orientation

By default, the toggle group is assumed to be horizontal. To change the
orientation to vertical, set the `orientation` property in the machine's context
to `vertical`.

```jsx {2}
const service = useMachine(toggle.machine, {
  orientation: "vertical",
})
```

### Listening for value changes

When the pressed toggle in the group changes, `onValueChange` callback is
invoked.

```jsx {2-4}
const service = useMachine(toggle.machine, {
  onValueChange(details) {
    // details => { value: string[] }
    console.log(details.value)
  },
})
```

### Allowing multiple selection

Set the `multiple` property in the machine's context to `true` to allow multiple
options to be toggled.

```jsx {2}
const service = useMachine(toggle.machine, {
  multiple: true,
})
```

### Disabling the toggle group

Set the `disabled` property in the machine's context to `true` to disable the
toggle group.

```jsx {2}
const service = useMachine(toggle.machine, {
  disabled: true,
})
```

### Disabling a toggle

Set the `disabled` property in the `getToggleProps` function to `true` to
disable a toggle.

```jsx
//...
<div {...api.getRootProps()}>
  <button {...api.getToggleProps({ value: "bold", disabled: true })}>B</button>
</div>
//...
```

### Disabling focus loop

The toggle group loops keyboard navigation by default. To disable this, set the
`loop` property in the machine's context to `false`.

```jsx {2}
const service = useMachine(toggle.machine, {
  loop: false,
})
```

### Disabling roving focus management

The toggle group uses roving focus management by default. To disable this, set
the `rovingFocus` property in the machine's context to `false`.

```jsx {2}
const service = useMachine(toggle.machine, {
  rovingFocus: false,
})
```

## Styling Guide

Earlier, we mentioned that each toggle group part has a `data-part` attribute
added to them to select and style them in the DOM.

### Pressed State

The toggle is pressed, the `data-state` attribute is applied to the toggle
button with `on` or `off` values.

```css
[data-part="toggle"][data-state="on|off"] {
  /* styles for toggle button */
}
```

### Focused State

When a toggle button is focused, the `data-focus` is applied to the root and
matching toggle button.

```css
[data-part="root"][data-focus] {
  /* styles for the root */
}

[data-part="toggle"][data-focus] {
  /* styles for the toggle */
}
```

### Disabled State

When a toggle button is disabled, the `data-disabled` is applied to the root and
matching toggle button.

```css
[data-part="root"][data-disabled] {
  /* styles for the root */
}

[data-part="toggle"][data-disabled] {
  /* styles for the toggle */
}
```

## Methods and Properties

### Machine Context

The toggle group machine exposes the following context properties:

<ContextTable name="toggle-group" />

### Machine API

The toggle group `api` exposes the following methods:

<ApiTable name="toggle-group" />

### Data Attributes

<DataAttrTable name="toggle-group" />

## Accessibility

Uses
[roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/radio/radio.html)
to manage focus movement among items.

### Keyboard Interactions

<KeyboardTable name="toggle-group" />
